Whenever PowerScan calls your preprocessor your resource file will be first in the resource path.
It is possible that several scans run simultaneously so your preprocessor must be prepared to get called for different files in any order. Currently PowerScan calls the preprocessor repeatedly for one archive file to extract all contents before processing another file but that may change in the future. Use the file refCon fields (described below) to store reference numbers of the files that your preprocessor has opened.
Resources
Your preprocessor addin file must have type ’PScP’ and creator ’PScn’. In the resource fork you will need these resources:
resource type
resource ID
contents
PScP
128
code for your preprocessor; entrypoint must be at the beginning; PowerScan will load and lock this resource at launch time
PSpi
128
info resource (use included ResEdit™ template)
icon suite
(ICN#, icl4, icl8, ics#, ics4, ics8)
128
icon suite for your preprocessor
STR#
128
Short info text displayed in Preferences dialog box when user clicks “Info” button.
The code resource must have its entrypoint at the beginning. It should be defined as:
The selector field, param1 and param2 pointers and the refCon field are described below. The PPType field holds a four-character code that uniquely identifies your preprocessor. The unique code is used to prevent several copies of the same preprocessor to be installed simultaneously. Note that PowerScan currently only allows one preprocessor in each addin file but that this may change in the future.
The info resource includes fields that tell PowerScan the name of your preprocessor, what file types it is interested in, and more. Use the ResEdit™ template that is included.
Selectors
These selectors are used when PowerScan communicates with your preprocessor addin:
selector
param1
param2
refCon
kPPAddinLoad
unused (nil)
unused (nil)
free for use
kPPAddinPreprocessFile
tFileInfoPtr
tArchiveScanPtr
free for use
kPPAddinCleanup
unused (nil)
unused (nil)
free for use
kPPAddinLoad
Your preprocessor will get a kPPAddinLoad message when PowerScan opens it. This will happen once for every preprocessor whether it is disabled or not (in the Preferences dialog box). Disabling or enabling a preprocessor during runtime will not cause any messages to be sent.
This is a good time to allocate memory that your preprocessor needs. Use the refCon field for holding your global data.
kPPAddinPreprocessFile
Whenever PowerScan finds a file that should be preprocessed by your addin it will send this message. The first parameter, param1, is a pointer to a tFileInfo data structure which contains data about the file. The second parameter, param2, points to a tArchiveScanRecord data structure which is used to return several files from the single input file.
When returning a tFileInfo record you should set the dirID and vRefNum fields to the directory ID and volume reference number for the file you return. If this file is part of an archive you can set both fields to 0 to indicate that the file doesn’t exist on the disk.
Set iconType to either iconApplication, iconDocument or iconFolder. PowerScan will convert these to corresponding archive icons if needed. The indentLevel counter should be increased when you go down one folder level and decreased when you leave a folder.
The crDateStr and mdDateStr strings will be generated by PowerScan from the corresponding numeric fields. Just leave these strings untouched and everything will work fine. Leave the selected field untouched as well.
The fileIndex field of the tArchiveScanRecord record will be set to 0 (zero) by PowerScan before the first call. The preprocessor should set this field to any other value (presumably 1) if it wants to return any more tFileInfo records. PowerScan will then call the preprocessor repeatedly until the fileIndex field is 0 or negative. The preprocessor can use this field as an index counter for the archive that it is processing (hence the name fileIndex).
If the preprocessor returns a negative value in the fileIndex field, PowerScan will not add any file at all. For example, it is possible to write a filter that makes all alias files invisible to PowerScan in this way.
The refCon field in the tArchiveScanRecord (which has nothing to do with the global refCon field) can be used for e.g. storing the reference number of the currently open archive file. As mentioned earlier PowerScan may in the future call your preprocessor with different files in any order so use this field to distinguish among the files your preprocessor is working on.
kPPAddinCleanup
When PowerScan quits it will send a kPPAddinCleanup message before it closes the preprocessor resource file. As with the kPPAddinLoad message this will happen even if the preprocessor is disabled.
You should dispose of any memory that was allocated at startup.
Some Type Definitions
Note See the included interface file for complete definitions.
{--record used when preprocessing an archive that contain multiple files--}
tArchiveScanRecord = record
fileIndex: integer;
refCon: longint;
end;
tArchiveScanPtr = ^tArchiveScanRecord;
Examples
Example 1
Suppose your preprocessor is interested in alias files. When PowerScan finds an alias file it will call your preprocessor like this:
• selector = kPPAddinPreprocessFile param1 = tFileInfo for the alias file param2 = tArchiveScanRecord with fileIndex = 0 and refCon = 0
You can now resolve the alias and fill the tFileInfo record with information from the new file. You will not need to touch the indentLevel field as it is filled in for you. Set the fileIndex field to 0.
Example 2
Suppose your preprocessor reads Compact Pro archives and that PowerScan scans this file:
MyArchive.cpt – FirstFile – SecondFile
Then your filter would get called in this way:
• selector = kPPAddinPreprocessFile param1 = tFileInfo for MyArchive.cpt param2 = tArchiveScanRecord with fileIndex = 0 and refCon = 0
Your filter should open the file MyArchive.cpt and store the reference number in the refCon field. You won’t need to do any additional processing of the file at this point but you should set the fileIndex field to 1.
• selector = kPPAddinPreprocessFile param1 = tFileInfo for MyArchive.cpt param2 = tArchiveScanRecord with fileIndex = 1 and refCon = whatever you stored here
Fill in the tFileInfo record for the first file in the opened archive (don’t forget to increase the indentLevel counter one step) and set fileIndex to 2.
• selector = kPPAddinPreprocessFile param1 = tFileInfo for MyArchive.cpt param2 = tArchiveScanRecord with fileIndex = 2 and refCon = whatever you stored here
Fill in the tFileInfo record for the second file in the opened archive, close the archive and set fileIndex to 0 to indicate that there are no more files in the archive.
